home *** CD-ROM | disk | FTP | other *** search
/ Creative Computers / Creative Computers CD-ROM, Volume 1 (Legendary Design Technologies, Inc.)(1994).iso / commercial / sunrize / psound_3.1 / public_domain / noisy / noisy_lib.doc < prev    next >
Text File  |  1994-11-17  |  6KB  |  178 lines
  1. Included on Perfect Sound master disk with Permission from the Author
  2.  
  3.  
  4.           noisy.library docs
  5.       Copyright © 1990, W. W. Howe
  6.           All Rights Reserved
  7.  
  8.  
  9.   "Noisy" is an Amiga runtime library designed to ease the task of
  10. creating and playing sampled and other sounds from any program. Written
  11. entirely in 68000 assembler, this small (2300 byte) library handles the
  12. tasks of parsing 8SVX (IFF) sound files, managing memory allocations
  13. and interfacing to the audio.device. All these functions are accomplished
  14. through the following calls:
  15.  
  16.  
  17.    *   Key = LoadSound(Name, Flags)
  18.  
  19.  
  20.    This function takes a filename and attempts to load the file into
  21. a chip ram buffer for subsequent playing. If successful, A 'Key' necessary
  22. for other library calls for that sound file is returned. Any problem, such
  23. as an absent file, will return a invalid Key of 0.
  24.  
  25.    Although the loader understands and accepts IFF sound files, any file
  26. may be loaded via this call. If it isn't an IFF sound file, it is loaded
  27. as if it was a raw sound file. So you can play anything, even your
  28. startup-sequence. 
  29.  
  30.    IFF files use a Period computed from the samples_per_second within
  31. the file, and the volume specified. Raw and other non-IFF files have a
  32. default of 64 (full) for the volume and 357 [10,000 samples_per_second]
  33. for the period.
  34.  
  35.    Sounds loaded with this call may be played again and again until
  36. removed with the UnLoadSound() call.
  37.  
  38.    The 'Flags' parameter is reserved for possible future enhancements, it
  39. should currently always be set to 0.
  40.  
  41.  
  42.  
  43. *         UnLoadSound(Key)
  44.  
  45.  
  46.    This call frees the memory and facilities allocated for a particular
  47. sound represented by the 'Key' returned from a call to LoadSound(). Once
  48. called, the key is no longer a valid key for future calls.
  49.  
  50.  
  51.  
  52. *   Key = CreateSound(mem_ptr, Length, Flags)
  53.  
  54.  
  55.    The CreateSound() function is designed to add a sound to the internal
  56. list used by PlaySound() from a memory area rather than from a disk file.
  57. The volume and period are set to the same defaults as raw sound files,
  58. and a Key is returned.
  59.  
  60.    This function allocates chip memory and copies the original area, making
  61. it unnecessary to utilize chip memory to create special waves.
  62.  
  63.   
  64.  
  65. *         DeleteSound(Key)
  66.  
  67.  
  68.    This call frees the memory and facilities allocated for a particular
  69. sound represented by the 'Key' returned from a call to CreateSound(). Once
  70. called, the key is no longer a valid key for future calls.
  71.  
  72.  
  73.  
  74. *   Err = PlaySound(Key)
  75.  
  76.  
  77.    This is the real business end of the whole library. You call this with a
  78. valid Key obtained from one of the previous calls and either have the
  79. sound play or an non-zero error value is returned.
  80.  
  81.  
  82. *   Old = SetPeriod(Key, Period)
  83.  
  84.  
  85.    This call changes the Period for a particular sound and returns the old
  86. period value. The Period is a number computed by dividing 3579545 by the
  87. samples per second. So 10000 samples_per_second equals a Period of 357.
  88. The range is limited to 148 to 65535 for the Period value. An invalid
  89. value will leave the current value unchanged and will return -1.
  90.  
  91.  
  92.  
  93. *   Old = SetVolume(Key, Period)
  94.  
  95.  
  96.    This call changes the Volume for a particular sound and returns the old
  97. Volume value. Range is from 0 (off) to 64 (full Volume). An invalid
  98. value will leave the current value unchanged and will return -1.
  99.  
  100.  
  101.  
  102. *   Old = SetCycles(Key, Period)
  103.  
  104.  
  105.    This call changes the Cycles for a particular sound and returns the old
  106. Cycles value. By default, a cycle of 1 is setup for each sound, and it will
  107. be played once. By using this function, you can make a sound play more than
  108. once per call from PlaySound(). Valid counts are in the range of 1 to
  109. 65535, and zero, which plays 65536 times. An invalid value will leave the
  110. current value unchanged and will return -1.
  111.  
  112.  
  113.  
  114. *         PanicRecovery()
  115.  
  116.  
  117.    This is a dangerous call. It walks the internal lists and frees all
  118. the resources allocated. The danger is that a program may be holding
  119. some keys and a library vector, and be expecting to use the library and
  120. play sounds, and this call makes it possible for the library to be
  121. expunged (this call does not expunge the library itself) thus, in effect,
  122. pulling the rug out from under the program.
  123.  
  124.    On the other hand, this call makes it possible to recover resources
  125. left open by a program that misbehaved, i.e. Loaded some sounds and
  126. then for whatever reason exited without calling the UnLoadSound() function
  127. for one or more.
  128.  
  129.    The best use is to make a small program that opens the library, calls
  130. this function, and then closes the library and exits. Run this new
  131. program only when you need to clean up after an errant program. There is
  132. a small program (FreeLibDanger) distributed in this package that does just
  133. that. Use it wisely, otherwise, please don't complain about it.
  134.  
  135.  
  136.          INSTALLATION:
  137.  
  138.    Copy noisy.library and noisy.bmap to the LIBS: directory. A smaple
  139. basic program using the library, LibTest.Bas has been included. It requires
  140. the file hal.snd (also included) be in the current directory along with
  141. the program.
  142.  
  143.  
  144.          MISCELLANEOUS:
  145.  
  146.  
  147.   For some reason I have been unable to ascertain, the library crashes
  148. whenever a fifth attenpt to allocate a sound channel (there are only
  149. four sound channels in the Amiga) is performed. It appears to be in the
  150. OpenDevice() call, but whether it is due to my programming or a problem
  151. in the OS remains to be determined.
  152.  
  153.    To work around this, I have placed code to prevent more than 4 sounds
  154. to be played via the library simultaneously. A fifth call to PlaySound()
  155. before any of the previous four have finished will simply return with an
  156. error code.
  157.  
  158.  
  159.          ERROR VALUES:
  160.  
  161.  
  162.    Returns from PlaySound():
  163.  
  164.  
  165.    100 = Library Initialization problem (No DOS)
  166.  
  167.     99 = Memory shortage
  168.  
  169.     98 = Invalid key passed
  170.  
  171.     97 = No audio channels available
  172.  
  173.    -11 = Allocation failed.
  174.  
  175.  
  176.    <* Wesley Howe *>
  177.  
  178.